This page is mainly intended to describe UEFI for Debian purposes: what's supported in Debian and how to use it, plus some troubleshooting tips.

See the Wikipedia page for vastly more information about it in general, or there's lots of other information in the Links section below.

Contents

(U)EFI stands for (Unified) Extensible Firmware Interface. It's a standard specification for the firmware interface on a computer, and it has been implemented by multiple vendors on various platforms.

See Grub2#UEFI_vs_BIOS_boot for a comparison of BIOS and UEFI boot via GRUB, the default bootloader in Debian.

UEFI started life as Intel's EFI specification. It was first seen in the wild on Itanium (ia64) machines and that's where Debian's first support started too.

Later, Intel passed control over the EFI specification to the UEFI Forum and they continued developing newer versions of the specification. The U for Unified was added to the name at this point. In most references here and elsewhere on the net, EFI and UEFI are interchangeable terms to describe the same thing.

There are multiple further bits of terminology here, and things are often confused. So let's explain!

UEFI is actually a set of interface specifications, nothing more.

The reference implementation of the UEFI specifications is called edk2 or EDK II (EFI Development Kit, version 2). Code can be found at https://github.com/tianocore/edk2 .

Tianocore is the name of the upstream development group working on the Open Source EDK II project - see https://www.tianocore.org/ for more information.

OVMF (Open Virtual Machine Firmware) is a build of edk2 designed to be used as firmware for a virtual machine.

Many commercial UEFI firmware implementations are built on top of edk2, with changes commonly being made to add platform initialisation and a pretty GUI on the front end.

UEFI has been supported to some extent on 5 of Debian's architectures:

64-bit Itanium (ia64 in Debian)

64-bit x86-64 (amd64)

32-bit x86 (i386)

32-bit ARM (armhf)

64-bit Aarch64 (arm64)

There are some caveats, though...

It's a fair bet to assume that RISC-V might end up with UEFI support in the future too.

On the PC architectures (amd64 and i386), UEFI-based firmware is a relatively new replacement for the ancient BIOS (Basic Input/Output System) that has existed ever since the PC was first developed in the 1980s. The old BIOS systems have strict limitations due to their ancient design, running in 16-bit mode with access to only 1MB of memory, and limited access to other resources like disks. UEFI firmware is normally fully native and so should be able to access all the system memory and all the devices.

Starting with Windows 8 (released on October 2012) most Desktop PC have UEFI as firmware instead of the legacy BIOS.

Some earlier PCs with UEFI had buggy UEFI. (See workaround 1 and workaround 2)

For the sake of backwards compatibility, many current PCs using UEFI also include a Compatibility Support Module (CSM), extra support code that will continue to boot in the old BIOS style. Over time, this support will most likely be phased out. Some systems were already being sold UEFI-only (i.e. with no CSM) in 2014.

(As for another timing reference to assess PC age, Windows 10 came to market in 2015.)

x86 virtual machines can be run using qemu with either BIOS or UEFI firmware. qemu will default to BIOS using SeaBIOS, but it can also run OVMF. Debian includes builds of OVMF for amd64 in the ovmf package.

Some Aarch64 machines (arm64) use U-Boot or other options like Fastboot for their firmware, but most general-purpose arm64 machines (e.g. those intended for use as servers) should be expected to use UEFI, typically via a build of edk2.

Debian includes edk2-based VM firmware for arm64 in the qemu-efi package. For some reason this is often described as AAVMF to distinguish it from OVMF for x86. It's basically the same software.

Most Arm machines (armhf) use U-Boot or other options like Fastboot for their firmware, but some machines can run edk2 as well directly.

Again, edk2 is also a good option for firmware for 32-bit Arm VMs. Debian includes this firmware in the qemu-efi-arm package.

Recent versions of U-Boot have also included some limited UEFI functionality. This is designed to be "just enough UEFI" to support common operations, without including a lot of the more complicated possibilities underneath.

Historically, the most common method of partitioning disks on PC platforms has been the MS-DOS standard using a Master Boot Record (MBR) and a tiny limited partition table with space to describe only 4 "primary" partitions. This is what BIOS systems still use to date. There are several important limitations that come with this scheme, but the most obvious one is the size limit of 2TB per disk. Back when this partitioning format was invented, a 100MB disk was large. Today, multi-terabyte disks are the norm.

UEFI also includes support for a newer partitioning format: the GUID Partition Table (GPT). It's much more flexible than the MS-DOS option, including:

Regular UEFI boot has several lists of possible boot entries, stored in UEFI config variables (normally in NVRAM), and boot order config variables stored alongside them. It allows for many different boot options, and a properly-defined fallback order. In many cases, you can even list and choose which OS / boot loader to use from the system boot menu (similar to the boot device menu implemented in many BIOSes). Unfortunately, a lot of PC UEFI implementations have got this wrong and so don't work properly.

The correct way for this to work when booting off local disk is for a boot variable to point to a vendor-specific bootloader program in

\EFI\$vendor\$bootloader.efi

on the EFI System Partition (ESP), a specially tagged partition which is normally formatted using FAT32.

Debian installs grub-efi for its EFI bootloader, as:

Architecture

Path

amd64

\EFI\debian\grubx64.efi

i386

\EFI\debian\grubia32.efi

arm64

\EFI\debian\grubaa64.efi

armhf

\EFI\debian\grubarm.efi

Each version of GRUB here contains all the code and configuration that GRUB needs to work from that point.

By using separate vendor directories like this, UEFI allows for clean interoperability between vendors. If only the firmware developers were competent... Some implementations ignore the boot order altogether, some filter it and will only run things that claim to be "Windows", etc. See below for tips on how to work around some of the known bugs in broken UEFI implementations.

If there are no boot variables pointing to a bootloader program in the ESP, or if the user has told the system appropriately, it will look for bootloaders in certain specific paths too. On each device, it will look for FAT32 filesystems. Within each of those, it will look for a specifically-named bootloader file, again with a different name per architecture:

Architecture

Path

amd64

\EFI\boot\bootx64.efi

i386

\EFI\boot\bootia32.efi

arm64

\EFI\boot\bootaa64.efi

armhf

\EFI\boot\bootarm.efi

The different names are deliberate - it allows for one disk or CD to contain boot files for multiple architectures with no clashes.

On Debian installation media, each of these files is again a copy of grub-efi with sufficient built-in code and configuration to find the rest of the system from there.

debian-installer's support for UEFI is mostly contained in two modules.

First comes the partman-efi module, and this will be loaded automatically if d-i recognises it has been booted in UEFI mode. partman-efi will cope with both MS-DOS and GPT partitioned disks, but will offer to use GPT by preference on disks that are not already partitioned. It knows how to set up an ESP with appropriate partition type and filesystem if necessary, and will ensure it's correctly mounted on the installed system later. If the system already has an ESP, partman-efi will attempt to use that rather than create a new one. This is for interoperability with existing operating systems in dual-boot systems.

Once the normal installation process has been completed, the second major component with UEFI support comes into play: grub-installer. It will install the grub-efi bootloader to the right location in the ESP and will use efibootmgr to register that bootloader with the firmware. On correctly-working systems, this should work without needing any user interaction. This module will automatically find the ESP and install its files in the right place, leaving no space for confusion on where boot files are saved (as can happen with MBR/MS-DOS systems).

The initial support to make UEFI amd64 systems directly installable in Debian was added in Wheezy (7.0, released on May 2013). Support was later added for i386 and arm64 systems for Jessie (8.0, released on April 2015), along with a number of quirks and bug workarounds. See below for more details about those. Support for armhf was added in Buster (10.0, released on July 2019).

The Linux kernel gives access to the UEFI configuration variables via a set of files under /sys, using two different interfaces.

The older interface was efivars, showing files under /sys/firmware/efi/vars, and this is what was used by default in both Wheezy (7.0, released on May 2013) and Jessie (8.0, released on April 2015).

The new interface is efivarfs, which will expose things in a slightly different format under /sys/firmware/efi/efivars. This is the new preferred way of using UEFI configuration variables, and Debian switched to it by default from Stretch onwards.

The exact details of these interfaces are hidden from view somewhat by efibootmgr and efivar, userland software packages written to work with them. Initially, all of the code was written directly in efibootmgr but more recently the lower-level code has been split out into the library efivar to make it easier to share this code with other utilities like fwupd. Read the man pages for these for full details, but here are a couple of examples from a system with many devices:

The same as example 1, but with more detail (including the GUIDs used to identify devices).

Create a new boot entry, pointing to a bootloader program on disk /dev/sdb, partition 1; write a new signature to the MBR if needed; call it "debian"; the bootloader program is in \EFI\debian\grubx64.efi

Initial support for UEFI installation was added for amd64 in Wheezy (7.0, released on May 2013). This worked for many users, but various users reported issues. Most of these were not directly bugs in Debian's UEFI support, but nonetheless we have added workarounds to help these people.

Quite a number of early UEFI systems were shipped with a non-UEFI installation of Windows 7 (released on October 2009) pre-installed, and the firmware set up to attempt UEFI boot first and BIOS boot second. This worked fine for users, but the moment a new operating system was installed alongside that copy of Windows, it would be difficult/impossible to dual-boot it.

debian-installer will now warn the user if it is booted in UEFI mode but can find it only non-UEFI existing OS installations. It gives them the option to switch the installer to non-UEFI mode from this point forwards so they don't break potential dual-boot setup.

(763127)

Many UEFI firmware implementations are unfortunately buggy, as mentioned earlier. Despite the specification for boot entries and boot order being quite clear about how things should work, there are lots of systems in the wild which get it wrong. Some systems simply ignore valid requests to add new boot entries. Others will accept those requests, but will refuse to use them unless they describe themselves as "Windows" or similar. There are lots of other similar bugs out there, suggesting that many system vendors have done very little testing beyond "does it work with Windows?"

As described above, on a UEFI system bootloaders should be installed only in the correct vendor-specific directory in the EFI System Partition (ESP). But, because of the buggy firmware implementations out there, operating system distributors cannot necessarily expect that this will work correctly for all systems. Microsoft have worked around this (and arguably also made the problem worse) - the Windows installer also installs to the removable media path in the ESP (e.g. \EFI\boot\bootx64.efi for amd64/X64 systems). All firmware implentations have to use this path to be able to run an OS installer. This means that Windows will always work on all these broken implementations, but it also means that system vendors can get away with shipping broken implementations. It removes the idea of having a fallback boot path and sensible control of boot order.

All OS installers installing things to this removable media path will conflict with any other such installers, which is bad and wrong. That's why in Debian we don't do this by default.

However, to help support those unfortunate people who own buggy systems like this there is an option to force grub-efi installation to the removable media path too. There is a d-i Rescue Mode option to force this - if you've just installed Debian on your UEFI system but it won't boot Debian afterwards, this may fix the problem for you. It can also be selected during the normal installation run using Expert mode, or preseed users can add the following option in their configuration (for amd64, tweak the package name to suit on other architectures):

grub-efi-amd64  grub2/force_efi_extra_removable boolean true

You can also select this by using dpkg-reconfigure grub-efi-amd64. Among other questions asked, this is the one to look for:

(746662)

If a bootable Debian Installer image is not available, then as a temporary measure copy \EFI\debian\grubx64.efi to \EFI\boot\bootx64.efi using whatever means are available (other operating system, connect the storage device to a different computer, etc.) and you should be able to get into your system. Once you have it booting normally, you should reconfigure grub as above so that your Debian system will know to do this in future too.

WARNING! If you don't reconfigure grub appropriately here, then on future upgrades the grub packages will not know to update the copy in the removable media path. This may leave you with an unbootable system at some point as grub changes happen.

As the name implies, installing grub-efi to the removable media path can be useful (or even necessary) for portable Debian installations on removable media.

Some UEFI system (e.g., Sony VAIO systems produced around 2013) doesn't allow selecting boot loader PATH. Some people claim success of dual boot by manually diverting and replacing files from rescue system prompt. For example:

This installation approach is not robust one for upgrade and it may be better to use the legacy MBR based installation approach, instead, or use removable media as above.

In Wheezy (Debian 7.0, released on May 2013), i386 UEFI support was intentionally omitted for a variety of reasons. However, since then lots more UEFI-only x86 machines were produced so we enabled it. Since Debian Jessie (8.0, released on April 2015), all standard i386 Debian installation media should work for UEFI installation as well as in BIOS mode, just like on amd64.

Some systems have been released containing 64-bit Intel Atom CPUs (such as the Bay Trail), but unfortunately use 32-bit UEFI firmware with no BIOS compatibility mode. Using the 32-bit UEFI x86 support, an i386 installation should be possible on these machines but it won't make the most of the 64-bit hardware.

Debian Jessie (8.0, released on April 2015) was the first Linux distribution to include full support for mixed-mode UEFI installation on these machines. The multi-arch installation media (available in netinst form) include the UEFI boot loaders necessary for both i386 and amd64 boot. By selecting "64-bit install" from the initial boot menu, debian-installer will install a 64-bit (amd64) version of Debian. The system will automatically detect that the underlying UEFI firmware is 32-bit and will install the appropriate version of grub-efi to work with it.

Although Debian releases since Wheezy (Debian 7.0, released on May 2013) have included general UEFI support, there were some features that have were not implemented immediately.

Since the first release of Stretch (9.0), UEFI has been supported on both installation and live images.

In previous releases UEFI support existed only in Debian's installation images. The accompanying live images did not have support for UEFI boot.

Debian has supported UEFI Secure Boot from Buster (10.0, released on July 2019) onwards for amd64, i386 and arm64. See SecureBoot for more details on how this works. It is supported for all the installation media and live media that we create for these three platforms.

This is arguably a mis-design in the UEFI specification - the ESP is a single point of failure on one disk. For systems with hardware RAID, that will provide some backup in case of disk failure. But for software RAID systems there is currently no support for putting the ESP on two separate disks in RAID. There is a way to do something useful with fallback options: add a grub hook to copy over any change to the EFI partition. Obviously, this will only handle the Debian part of things, and will not handle any other OS that you may be multi-boot on. First, make sure both of your efi partition (on both disks where you're running RAID on) are mounted. Add the 2nd drive to the fstab if it's not there. Note that using UUID is recommended, as well as the nofail option (to gracefully boot if one drive is missing);

Then a grub hook like this one may come to the rescue:

See GrubEFIReinstall

Due to high latency, EFI variable access is apparently disabled by default on RT kernel (see patch). You could enable things by passing kernel command line efi=runtime

The Debian installer splash screen will say it's the UEFI installer, and will look slightly different to the equivalent screen in BIOS mode. BIOS boot is done via isolinux/syslinux, but UEFI boot is done using grub.

BIOS boot in d-i

UEFI boot in d-i

Later on, the thing to look for is the directory /sys/firmware/efi. If that exists, the system is running in UEFI mode.

efibootmgr is your friend. Run it without parameters to simply list the boot options and boot order on your system, or add -v for more detail of where each boot entry points.

After that, check to see if you have Secure Boot enabled - we didn't support Secure Boot until version 10.0 (Buster, released on July 2019).

If that still doesn't help, you may have a buggy firmware implementation. Try installing to the removable media path - see above for instructions.

There are a few circumstances that can cause this problem:

A common cause on x86 PC-type systems is using an EFI System Partition that is not accessible to the firmware (e.g by using Software RAID for the ESP). This will show errors like the following:

Workaround

It's possible for systems to use up all the UEFI variable space so that they can't write new boot variables. The errors here may look confusingly like a filesystem has filled up:

This problem can be caused by firmware bugs, or occasionally other software filling up the variable space (e.g. /sys/fs/pstore filling up with crash dumps.

See https://blogs.oracle.com/linux/post/pstore-linux-kernel-persistent-storage-file-system for more information about pstore if you need it.

Workaround

Another common cause for failure here is firmware that supports some of the UEFI interfaces needed for boot, but not runtime setting of UEFI boot variables. This is (currently) most commonly seen on smaller arm64 systems that use U-Boot, e.g. the Rock64. This will look something like:

Workaround

In all of these cases, the easiest workaround is to tweak configuration for grub-efi-ARCH using dpkg-reconfigure. As already mentioned earlier, it is possible to configure Debian's grub-efi packages to install to the removable media path. It's also possible to tell them to not attempt to update UEFI boot variables in the NVRAM:

Doing both of these will stop the errors here. We hope that in future these workarounds will not be necessary, at least for most users.

There are lots of other UEFI resources on the internet. Particularly useful ones include:

http://www.uefi.org/ - the UEFI Forum

http://wiki.osdev.org/UEFI - OSDev wiki page about UEFI

http://wiki.osdev.org/Broken_UEFI_implementations - wiki page for Linux distro vendors to share information about systems with broken UEFI implementations

The best place to talk about UEFI support in Debian is the mailing list: mailto:[email protected] (web archive) or in our IRC channel: irc://irc.debian.org/#debian-efi.

CategoryBootProcess CategoryHardware